<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="module-cgi.html" />
<link rel="prev" href="internet.html" />
<link rel="parent" href="internet.html" />
<link rel="next" href="browser-controllers.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>18.1 webbrowser -- Convenient Web-browser controller</title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="18. internet Protocols and"
  href="internet.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="18. internet Protocols and"
  href="internet.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="18.1.1 browser Controller Objects"
  href="browser-controllers.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="internet.html">18. Internet Protocols and</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="internet.html">18. Internet Protocols and</a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="browser-controllers.html">18.1.1 Browser Controller Objects</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h1><a name="SECTION0020100000000000000000">
18.1 <tt class="module">webbrowser</tt> --
         Convenient Web-browser controller</a>
</h1>

<p>
<a name="module-webbrowser"></a>

<p>
The <tt class="module">webbrowser</tt> module provides a high-level interface to
allow displaying Web-based documents to users. Under most
circumstances, simply calling the <tt class="function">open()</tt> function from this
module will do the right thing.

<p>
Under <span class="Unix">Unix</span>, graphical browsers are preferred under X11, but text-mode
browsers will be used if graphical browsers are not available or an X11
display isn't available.  If text-mode browsers are used, the calling
process will block until the user exits the browser.

<p>
If the environment variable <a class="envvar" id='l2h-3801' xml:id='l2h-3801'>BROWSER</a> exists, it
is interpreted to override the platform default list of browsers, as a
os.pathsep-separated list of browsers to try in order.  When the value of
a list part contains the string <code>%s</code>, then it is 
interpreted as a literal browser command line to be used with the argument URL
substituted for <code>%s</code>; if the part does not contain
<code>%s</code>, it is simply interpreted as the name of the browser to
launch.

<p>
For non-<span class="Unix">Unix</span> platforms, or when a remote browser is available on
<span class="Unix">Unix</span>, the controlling process will not wait for the user to finish
with the browser, but allow the remote browser to maintain its own
windows on the display.  If remote browsers are not available on <span class="Unix">Unix</span>,
the controlling process will launch a new browser and wait.

<p>
The script <b class="program">webbrowser</b> can be used as a command-line interface
for the module. It accepts an URL as the argument. It accepts the following
optional parameters: <b class="programopt">-n</b> opens the URL in a new browser window,
if possible; <b class="programopt">-t</b> opens the URL in a new browser page ("tab"). The
options are, naturally, mutually exclusive.

<p>
The following exception is defined:

<p>
<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-3795' xml:id='l2h-3795' class="exception">Error</tt></b></dt>
<dd>
  Exception raised when a browser control error occurs.
</dd></dl>

<p>
The following functions are defined:

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3796' xml:id='l2h-3796' class="function">open</tt></b>(</nobr></td>
  <td><var>url</var><big>[</big><var>, new=0</var><big>[</big><var>, autoraise=1</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  Display <var>url</var> using the default browser. If <var>new</var> is 0, the
  <var>url</var> is opened in the same browser window.  If <var>new</var> is 1,
  a new browser window is opened if possible.  If <var>new</var> is 2,
  a new browser page ("tab") is opened if possible.  If <var>autoraise</var> is
  true, the window is raised if possible (note that under many window
  managers this will occur regardless of the setting of this variable).

<span class="versionnote">Changed in version 2.5:
<var>new</var> can now be 2.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3797' xml:id='l2h-3797' class="function">open_new</tt></b>(</nobr></td>
  <td><var>url</var>)</td></tr></table></dt>
<dd>
  Open <var>url</var> in a new window of the default browser, if possible,
  otherwise, open <var>url</var> in the only browser window.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3798' xml:id='l2h-3798' class="function">open_new_tab</tt></b>(</nobr></td>
  <td><var>url</var>)</td></tr></table></dt>
<dd>
  Open <var>url</var> in a new page ("tab") of the default browser, if possible,
  otherwise equivalent to <tt class="function">open_new</tt>.

<span class="versionnote">New in version 2.5.</span>

</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3799' xml:id='l2h-3799' class="function">get</tt></b>(</nobr></td>
  <td><var></var><big>[</big><var>name</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  Return a controller object for the browser type <var>name</var>.  If
  <var>name</var> is empty, return a controller for a default browser
  appropriate to the caller's environment.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-3800' xml:id='l2h-3800' class="function">register</tt></b>(</nobr></td>
  <td><var>name, constructor</var><big>[</big><var>, instance</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
  Register the browser type <var>name</var>.  Once a browser type is
  registered, the <tt class="function">get()</tt> function can return a controller
  for that browser type.  If <var>instance</var> is not provided, or is
  <code>None</code>, <var>constructor</var> will be called without parameters to
  create an instance when needed.  If <var>instance</var> is provided,
  <var>constructor</var> will never be called, and may be <code>None</code>.

<p>
This entry point is only useful if you plan to either set the
  <a class="envvar" id='l2h-3802' xml:id='l2h-3802'>BROWSER</a> variable or call <tt class="function">get</tt> with a nonempty
  argument matching the name of a handler you declare.
</dl>

<p>
A number of browser types are predefined.  This table gives the type
names that may be passed to the <tt class="function">get()</tt> function and the
corresponding instantiations for the controller classes, all defined
in this module.

<p>
<div class="center"><table class="realtable">
  <thead>
    <tr>
      <th class="left"  >Type Name</th>
      <th class="left"  >Class Name</th>
      <th class="center">Notes</th>
      </tr>
    </thead>
  <tbody>
    <tr><td class="left"   valign="baseline"><code>'mozilla'</code></td>
        <td class="left"  ><tt class="class">Mozilla('mozilla')</tt></td>
        <td class="center"></td></tr>
    <tr><td class="left"   valign="baseline"><code>'firefox'</code></td>
        <td class="left"  ><tt class="class">Mozilla('mozilla')</tt></td>
        <td class="center"></td></tr>
    <tr><td class="left"   valign="baseline"><code>'netscape'</code></td>
        <td class="left"  ><tt class="class">Mozilla('netscape')</tt></td>
        <td class="center"></td></tr>
    <tr><td class="left"   valign="baseline"><code>'galeon'</code></td>
        <td class="left"  ><tt class="class">Galeon('galeon')</tt></td>
        <td class="center"></td></tr>
    <tr><td class="left"   valign="baseline"><code>'epiphany'</code></td>
        <td class="left"  ><tt class="class">Galeon('epiphany')</tt></td>
        <td class="center"></td></tr>
    <tr><td class="left"   valign="baseline"><code>'skipstone'</code></td>
        <td class="left"  ><tt class="class">BackgroundBrowser('skipstone')</tt></td>
        <td class="center"></td></tr>
    <tr><td class="left"   valign="baseline"><code>'kfmclient'</code></td>
        <td class="left"  ><tt class="class">Konqueror()</tt></td>
        <td class="center">(1)</td></tr>
    <tr><td class="left"   valign="baseline"><code>'konqueror'</code></td>
        <td class="left"  ><tt class="class">Konqueror()</tt></td>
        <td class="center">(1)</td></tr>
    <tr><td class="left"   valign="baseline"><code>'kfm'</code></td>
        <td class="left"  ><tt class="class">Konqueror()</tt></td>
        <td class="center">(1)</td></tr>
    <tr><td class="left"   valign="baseline"><code>'mosaic'</code></td>
        <td class="left"  ><tt class="class">BackgroundBrowser('mosaic')</tt></td>
        <td class="center"></td></tr>
    <tr><td class="left"   valign="baseline"><code>'opera'</code></td>
        <td class="left"  ><tt class="class">Opera()</tt></td>
        <td class="center"></td></tr>
    <tr><td class="left"   valign="baseline"><code>'grail'</code></td>
        <td class="left"  ><tt class="class">Grail()</tt></td>
        <td class="center"></td></tr>
    <tr><td class="left"   valign="baseline"><code>'links'</code></td>
        <td class="left"  ><tt class="class">GenericBrowser('links')</tt></td>
        <td class="center"></td></tr>
    <tr><td class="left"   valign="baseline"><code>'elinks'</code></td>
        <td class="left"  ><tt class="class">Elinks('elinks')</tt></td>
        <td class="center"></td></tr>
    <tr><td class="left"   valign="baseline"><code>'lynx'</code></td>
        <td class="left"  ><tt class="class">GenericBrowser('lynx')</tt></td>
        <td class="center"></td></tr>
    <tr><td class="left"   valign="baseline"><code>'w3m'</code></td>
        <td class="left"  ><tt class="class">GenericBrowser('w3m')</tt></td>
        <td class="center"></td></tr>
    <tr><td class="left"   valign="baseline"><code>'windows-default'</code></td>
        <td class="left"  ><tt class="class">WindowsDefault</tt></td>
        <td class="center">(2)</td></tr>
    <tr><td class="left"   valign="baseline"><code>'internet-config'</code></td>
        <td class="left"  ><tt class="class">InternetConfig</tt></td>
        <td class="center">(3)</td></tr>
    <tr><td class="left"   valign="baseline"><code>'macosx'</code></td>
        <td class="left"  ><tt class="class">MacOSX('default')</tt></td>
        <td class="center">(4)</td></tr></tbody>
</table></div>

<p>
Notes:

<p>
<dl>
<dt><strong>(1)</strong></dt>
<dd>``Konqueror'' is the file manager for the KDE desktop environment for
<span class="Unix">Unix</span>, and only makes sense to use if KDE is running.  Some way of
reliably detecting KDE would be nice; the <a class="envvar" id='l2h-3803' xml:id='l2h-3803'>KDEDIR</a> variable is
not sufficient.  Note also that the name ``kfm'' is used even when
using the <b class="program">konqueror</b> command with KDE 2 -- the
implementation selects the best strategy for running Konqueror.

<p>
</dd>
<dt><strong>(2)</strong></dt>
<dd>Only on Windows platforms.

<p>
</dd>
<dt><strong>(3)</strong></dt>
<dd>Only on MacOS platforms; requires the standard MacPython <tt class="module">ic</tt>
module, described in the <em class="citetitle"><a
 href="../mac/module-ic.html"
 title="Macintosh
Library Modules"
 >Macintosh
Library Modules</a></em> manual.

<p>
</dd>
<dt><strong>(4)</strong></dt>
<dd>Only on MacOS X platform.
</dd>
</dl>

<p>
Here are some simple examples:

<p>
<div class="verbatim"><pre>
url = 'http://www.python.org'

# Open URL in a new tab, if a browser window is already open. 
webbrowser.open_new_tab(url + '/doc')

# Open URL in new window, raising the window if possible.
webbrowser.open_new(url)
</pre></div>

<p>

<p><br /></p><hr class='online-navigation' />
<div class='online-navigation'>
<!--Table of Child-Links-->
<a name="CHILD_LINKS"><strong>Subsections</strong></a>

<ul class="ChildLinks">
<li><a href="browser-controllers.html">18.1.1 Browser Controller Objects</a>
</ul>
<!--End of Table of Child-Links-->
</div>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="18. internet Protocols and"
  href="internet.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="18. internet Protocols and"
  href="internet.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="18.1.1 browser Controller Objects"
  href="browser-controllers.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="internet.html">18. Internet Protocols and</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="internet.html">18. Internet Protocols and</a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="browser-controllers.html">18.1.1 Browser Controller Objects</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
